package edu.ccut.saturn.component;

import java.util.List;
import java.util.Set;

import org.apache.commons.jexl.JexlContext;

/**
 * 定义了在logic组件执行过程中用于共享信息的上下文类型的操作接口。
 * logic上下文对象的生命周期是伴随着组件运行开始而创建，伴随着组件运行结束而销毁，其内部维护着组件内各结点需要共享的信息。
 * 组件是无状态的但上下文对象中维护了组件在每次运行过程中的状态信息。
 * 
 * @author 谷钰
 * @version 1.0 2008.9.09
 * @see IParameterContext
 */
public interface ILogicContext {

	/**
	 * Get logic context unique Id
	 * 
	 * @return
	 */
	public String getId();
	
	/**
	 * Get value object by key
	 * 
	 * @param key
	 * @return
	 */
	public Object getValue(String key);
	
	public Object getValue(String key, int scope);

	/**
	 * Get value object by {@link IParameter}
	 * 
	 * @param parameterContext
	 * @return
	 */
	public Object getValue(IParameterInfo parameterInfo);

	/**
	 * Get value keys in scope
	 * 
	 * @param scope
	 * @return
	 */
	public Set<String> getValueKeys(int scope);

	/**
	 * Set value object
	 * 
	 * @param key
	 * @param value
	 */
	public void setValue(String key, Object value);

	/**
	 * Set value object by parameter
	 * 
	 * @param parameterInfo
	 */
	public void setValue(IParameterInfo parameterInfo, Object value);

	/**
	 * Create a {@link IParameterContext} by parameter List
	 * 
	 * @param parameterInfo
	 * @return
	 */
	public IParameterContext createParameterContext(
			List<IParameterInfo> parameterInfos)
			throws SaturnValidateFailedException, SaturnComponentException;

	/**
	 * Refresh logic context by parameterInfo List
	 * 
	 * @param parameterContext
	 */
	public void refreshContextFromParameterContext(
			List<IParameterInfo> parameterInfos,
			IParameterContext parameterContext);

	/**
	 * Get Jexl context for expression
	 * 
	 * @return
	 */
	public JexlContext getJexlContext();
	
	/**
	 * 获得上下文对象中维护的数据库代理对象，通过它可以获得数据库连接对象或执行事务相关操作。
	 * @return
	 */
	public DatabaseBroker getDatabaseBroker();

	/**
	 * 删除指定的数据域中的指定的变量
	 * @param key
	 * @param scope
	 */
	public void removeParameterKey(String key, int scope);

	/**
	 * 清空指定的数据域中的数据
	 * @param scope
	 */
	public void cleanScope(int scope);
	
	/**
	 * 设置某个结点的下一个运行结点的id。结点的下一运行结点可能会在组件的一次运行过程中发生变化，
	 * 因此把这个信息保存到上下文环境中。
	 * 
	 * @param id
	 * @param exceptionId
	 */
	public void setNodeRouter(String id, String exceptionId);
	
	/**
	 * 获得指定节点的下一运行结点id
	 * 
	 * @param id
	 * @return
	 */
	public String getNextNodeId(String id);
	
	/**
	 * 从上下文中删除指定结点的下一运行结点id
	 * 
	 * @param id
	 */
	public void removeExceptionRouter(String id);

	/**
	 * 创建参数上下文对象。参数上下文描述了action组件、logic组件、component组件运行时需要的输入输出参数信息。
	 * 
	 * @param parameterInfos
	 * @param transactionType
	 * @return
	 * @throws SaturnValidateFailedException
	 * @throws SaturnComponentException
	 */
	public IParameterContext createParameterContext(
			List<IParameterInfo> parameterInfos, String transactionType)
			throws SaturnValidateFailedException, SaturnComponentException;
	
	/**
	 * 获得事务类型信息
	 * @return
	 */
	public String getTransactionType();
	
	public ILogicContext newLogicContext();
}
